Developer CD Series 1999 July: Mac OS SDK

home *** CD-ROM | disk | FTP | other *** search

/ Developer CD Series 1999 July: Mac OS SDK / Dev.CD Jul 99 SDK1.toast / Development Kits / Mac OS / UPDATE- Int&Libs 3.2 / AIncludes / Multiprocessing.a < prev next >

Wrap

Text File | 1999-05-25 | 27.8 KB | 997 lines | [TEXT/MPS ]

; ; File: Multiprocessing.a ; ; Contains: Multiprocessing interfaces ; ; Version: Technology: Multiprocessing API version 2.0, integrated nanokernel support ; Release: Veronica Seed, Use with 3.2 Universal Interfaces ; ; Copyright: © 1996-1999 by Apple Computer, Inc. and © 1995-1997 DayStar Digital, Inc. ; ; Bugs?: For bug reports, consult the following page on ; the World Wide Web: ; ; http://developer.apple.com/bugreporter/ ; ; ; =========================================================================================== ; *** WARNING: You must properly check the availability of MP services before calling them! ; See the section titled "Checking API Availability". ; =========================================================================================== IF &TYPE('__MULTIPROCESSING__') = 'UNDEFINED' THEN __MULTIPROCESSING__ SET 1 IF &TYPE('__MACTYPES__') = 'UNDEFINED' THEN include 'MacTypes.a' ENDIF IF &TYPE('__CODEFRAGMENTS__') = 'UNDEFINED' THEN include 'CodeFragments.a' ENDIF IF &TYPE('__DRIVERSERVICES__') = 'UNDEFINED' THEN include 'DriverServices.a' ENDIF ; =========================================================================================== ; This is the header file for version 2.0 of the Mac OS multiprocessing support. This version ; has been totally reimplemented and has significant new services. The main goal of the ; reimplementation has been to transfer task management into the core operating system to provide ; much more reliable and more efficient operation, including on single processor machines. ; The memory management has also been massively improved, it is much faster and wastes much ; less space. New services include POSIX style per-task storage, timers with millisecond and ; microsecond resolutions, memory allocation at a specified alignment, and system pageable ; and RAM resident memory pools. See the MP API documentation for details. ; The old "DayStar" debugging services (whose names began with an underscore) have been ; removed from this header. A very few are still implemented for binary compatibility, or in ; cases where they happened to be exposed inappropriately. (E.g. _MPIsFullyInitialized must ; be called to see if the MP API is ReallyTruly™ usable.) New code and recompiles of old ; code should avoid use of these defunct services, except for _MPIsFullyInitialized. ; =========================================================================================== ; =========================================================================================== ; The following services are from the original MP API and remain supported in version 2.0: ; MPProcessors ; MPCreateTask ; MPTerminateTask ; MPCurrentTaskID ; MPYield ; MPExit ; MPCreateQueue ; MPDeleteQueue ; MPNotifyQueue ; MPWaitOnQueue ; MPCreateSemaphore ; MPCreateBinarySemaphore (In C only, a macro that calls MPCreateSemaphore.) ; MPDeleteSemaphore ; MPSignalSemaphore ; MPWaitOnSemaphore ; MPCreateCriticalRegion ; MPDeleteCriticalRegion ; MPEnterCriticalRegion ; MPExitCriticalRegion ; MPAllocate (Deprecated, use MPAllocateAligned for new builds.) ; MPFree ; MPBlockCopy ; MPLibraryIsLoaded (In C only, a macro.) ; _MPIsFullyInitialized (See comments about checking for MP API availability.) ; =========================================================================================== ; =========================================================================================== ; The following services are new in version 2.0: ; MPProcessorsScheduled ; MPSetTaskWeight ; MPTaskIsPreemptive ; MPAllocateTaskStorageIndex ; MPDeallocateTaskStorageIndex ; MPSetTaskStorageValue ; MPGetTaskStorageValue ; MPSetQueueReserve ; MPCreateEvent ; MPDeleteEvent ; MPSetEvent ; MPWaitForEvent ; UpTime ; DurationToAbsolute ; AbsoluteToDuration ; MPDelayUntil ; MPCreateTimer ; MPDeleteTimer ; MPSetTimerNotify ; MPArmTimer ; MPCancelTimer ; MPSetExceptionHandler ; MPThrowException ; MPDisposeTaskException ; MPExtractTaskState ; MPSetTaskState ; MPRegisterDebugger ; MPUnregisterDebugger ; MPAllocateAligned (Preferred over MPAllocate.) ; MPGetAllocatedBlockSize ; MPBlockClear ; MPDataToCode ; MPRemoteCall (Preferred over _MPRPC.) ; =========================================================================================== ; =========================================================================================== ; The following services are "unofficial" extensions to the original API. They are not in ; the multiprocessing API documentation, but were in previous versions of this header. They ; remain supported in version 2.0. They may not be supported in other environments. ; _MPRPC (Deprecated, use MPRemoteCall for new builds.) ; _MPAllocateSys (Deprecated, use MPAllocateAligned for new builds.) ; _MPTaskIsToolboxSafe ; _MPLibraryVersion ; _MPLibraryIsCompatible ; =========================================================================================== ; =========================================================================================== ; The following services were in previous versions of this header for "debugging only" use. ; They are NOT implemented in version 2.0. For old builds they can be accessed by defining ; the symbol MPIncludeDefunctServices to have a nonzero value. ; _MPInitializePrintf ; _MPPrintf ; _MPDebugStr ; _MPStatusPString ; _MPStatusCString ; =========================================================================================== ; § ; =========================================================================================== ; General Types and Constants ; =========================== MPLibrary_MajorVersion EQU 2 MPLibrary_MinorVersion EQU 0 MPLibrary_Release EQU 1 MPLibrary_DevelopmentRevision EQU 1 ; typedef CFragContextID MPProcessID kMPNoID EQU 0 ; New code should use kInvalidID everywhere. ; typedef OptionBits MPTaskOptions ; typedef UInt32 TaskStorageIndex ; typedef UInt32 TaskStorageValue ; typedef ItemCount MPSemaphoreCount ; typedef UInt32 MPTaskWeight ; typedef UInt32 MPEventFlags ; typedef UInt32 MPExceptionKind ; typedef UInt32 MPTaskStateKind ; typedef UInt32 MPDebuggerLevel kDurationImmediate EQU 0 kDurationForever EQU $7FFFFFFF kDurationMillisecond EQU 1 kDurationMicrosecond EQU -1 ; § ; =========================================================================================== ; Tasking Services ; ================ ; ; extern ItemCount MPProcessors(void ) ; IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN IMPORT_CFM_FUNCTION MPProcessors ENDIF ; The physical total. ; ; extern ItemCount MPProcessorsScheduled(void ) ; IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN IMPORT_CFM_FUNCTION MPProcessorsScheduled ENDIF ; Those currently in use. ; ------------------------------------------------------------------------------------------- ; ; extern OSStatus MPCreateTask(TaskProc entryPoint, void *parameter, ByteCount stackSize, MPQueueID notifyQueue, void *terminationParameter1, void *terminationParameter2, MPTaskOptions options, MPTaskID *task) ; IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN IMPORT_CFM_FUNCTION MPCreateTask ENDIF ; ; extern OSStatus MPTerminateTask(MPTaskID task, OSStatus terminationStatus) ; IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN IMPORT_CFM_FUNCTION MPTerminateTask ENDIF ; ; extern OSStatus MPSetTaskWeight(MPTaskID task, MPTaskWeight weight) ; IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN IMPORT_CFM_FUNCTION MPSetTaskWeight ENDIF ; ; extern Boolean MPTaskIsPreemptive(MPTaskID taskID) ; IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN IMPORT_CFM_FUNCTION MPTaskIsPreemptive ENDIF ; May be kInvalidID. ; ; extern void MPExit(OSStatus status) ; IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN IMPORT_CFM_FUNCTION MPExit ENDIF ; ; extern void MPYield(void ) ; IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN IMPORT_CFM_FUNCTION MPYield ENDIF ; ; extern MPTaskID MPCurrentTaskID(void ) ; IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN IMPORT_CFM_FUNCTION MPCurrentTaskID ENDIF ; ------------------------------------------------------------------------------------------- ; --------------------------------------------------- ; ! The task storage services are new in version 2.0. ; ; extern OSStatus MPAllocateTaskStorageIndex(TaskStorageIndex *index) ; IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN IMPORT_CFM_FUNCTION MPAllocateTaskStorageIndex ENDIF ; ; extern OSStatus MPDeallocateTaskStorageIndex(TaskStorageIndex index) ; IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN IMPORT_CFM_FUNCTION MPDeallocateTaskStorageIndex ENDIF ; ; extern OSStatus MPSetTaskStorageValue(TaskStorageIndex index, TaskStorageValue value) ; IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN IMPORT_CFM_FUNCTION MPSetTaskStorageValue ENDIF ; ; extern TaskStorageValue MPGetTaskStorageValue(TaskStorageIndex index) ; IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN IMPORT_CFM_FUNCTION MPGetTaskStorageValue ENDIF ; § ; =========================================================================================== ; Synchronization Services ; ======================== ; ; extern OSStatus MPCreateQueue(MPQueueID *queue) ; IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN IMPORT_CFM_FUNCTION MPCreateQueue ENDIF ; ; extern OSStatus MPDeleteQueue(MPQueueID queue) ; IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN IMPORT_CFM_FUNCTION MPDeleteQueue ENDIF ; ; extern OSStatus MPNotifyQueue(MPQueueID queue, void *param1, void *param2, void *param3) ; IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN IMPORT_CFM_FUNCTION MPNotifyQueue ENDIF ; ; extern OSStatus MPWaitOnQueue(MPQueueID queue, void **param1, void **param2, void **param3, Duration timeout) ; IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN IMPORT_CFM_FUNCTION MPWaitOnQueue ENDIF ; ; extern OSStatus MPSetQueueReserve(MPQueueID queue, ItemCount count) ; IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN IMPORT_CFM_FUNCTION MPSetQueueReserve ENDIF ; ------------------------------------------------------------------------------------------- ; ; extern OSStatus MPCreateSemaphore(MPSemaphoreCount maximumValue, MPSemaphoreCount initialValue, MPSemaphoreID *semaphore) ; IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN IMPORT_CFM_FUNCTION MPCreateSemaphore ENDIF ; ; extern OSStatus MPDeleteSemaphore(MPSemaphoreID semaphore) ; IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN IMPORT_CFM_FUNCTION MPDeleteSemaphore ENDIF ; ; extern OSStatus MPSignalSemaphore(MPSemaphoreID semaphore) ; IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN IMPORT_CFM_FUNCTION MPSignalSemaphore ENDIF ; ; extern OSStatus MPWaitOnSemaphore(MPSemaphoreID semaphore, Duration timeout) ; IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN IMPORT_CFM_FUNCTION MPWaitOnSemaphore ENDIF ; ------------------------------------------------------------------------------------------- ; ; extern OSStatus MPCreateCriticalRegion(MPCriticalRegionID *criticalRegion) ; IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN IMPORT_CFM_FUNCTION MPCreateCriticalRegion ENDIF ; ; extern OSStatus MPDeleteCriticalRegion(MPCriticalRegionID criticalRegion) ; IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN IMPORT_CFM_FUNCTION MPDeleteCriticalRegion ENDIF ; ; extern OSStatus MPEnterCriticalRegion(MPCriticalRegionID criticalRegion, Duration timeout) ; IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN IMPORT_CFM_FUNCTION MPEnterCriticalRegion ENDIF ; ; extern OSStatus MPExitCriticalRegion(MPCriticalRegionID criticalRegion) ; IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN IMPORT_CFM_FUNCTION MPExitCriticalRegion ENDIF ; ------------------------------------------------------------------------------------------- ; ; extern OSStatus MPCreateEvent(MPEventID *event) ; IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN IMPORT_CFM_FUNCTION MPCreateEvent ENDIF ; ; extern OSStatus MPDeleteEvent(MPEventID event) ; IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN IMPORT_CFM_FUNCTION MPDeleteEvent ENDIF ; ; extern OSStatus MPSetEvent(MPEventID event, MPEventFlags flags) ; IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN IMPORT_CFM_FUNCTION MPSetEvent ENDIF ; ; extern OSStatus MPWaitForEvent(MPEventID event, MPEventFlags *flags, Duration timeout) ; IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN IMPORT_CFM_FUNCTION MPWaitForEvent ENDIF ; § ; =========================================================================================== ; Timer Services ; ============== ; -------------------------------------------- ; ! The timer services are new in version 2.0. IF 0 THEN ; For now these are taken from DriverServices, should be in a better place. ; ; extern AbsoluteTime UpTime(void ) ; IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN IMPORT_CFM_FUNCTION UpTime ENDIF ; ; extern AbsoluteTime DurationToAbsolute(Duration duration) ; IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN IMPORT_CFM_FUNCTION DurationToAbsolute ENDIF ; ; extern Duration AbsoluteToDuration(AbsoluteTime time) ; IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN IMPORT_CFM_FUNCTION AbsoluteToDuration ENDIF ENDIF ; 0 ; For MPArmTimer options kMPPreserveTimerIDMask EQU $00000001 kMPTimeIsDeltaMask EQU $00000002 kMPTimeIsDurationMask EQU $00000004 ; ; extern OSStatus MPDelayUntil(AbsoluteTime *expirationTime) ; IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN IMPORT_CFM_FUNCTION MPDelayUntil ENDIF ; ; extern OSStatus MPCreateTimer(MPTimerID *timerID) ; IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN IMPORT_CFM_FUNCTION MPCreateTimer ENDIF ; ; extern OSStatus MPDeleteTimer(MPTimerID timerID) ; IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN IMPORT_CFM_FUNCTION MPDeleteTimer ENDIF ; ; extern OSStatus MPSetTimerNotify(MPTimerID timerID, MPOpaqueID notificationID, void *notifyParam1, void *notifyParam2, void *notifyParam3) ; IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN IMPORT_CFM_FUNCTION MPSetTimerNotify ENDIF ; ; extern OSStatus MPArmTimer(MPTimerID timerID, AbsoluteTime *expirationTime, OptionBits options) ; IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN IMPORT_CFM_FUNCTION MPArmTimer ENDIF ; ; extern OSStatus MPCancelTimer(MPTimerID timerID, AbsoluteTime *timeRemaining) ; IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN IMPORT_CFM_FUNCTION MPCancelTimer ENDIF ; § ; =========================================================================================== ; Memory Services ; =============== ; Maximum allocation request size is 1GB. kMPMaxAllocSize EQU 1073741824 ; Values for the alignment parameter to MPAllocateAligned. kMPAllocateDefaultAligned EQU 0 kMPAllocate8ByteAligned EQU 3 kMPAllocate16ByteAligned EQU 4 kMPAllocate32ByteAligned EQU 5 kMPAllocate1024ByteAligned EQU 10 kMPAllocate4096ByteAligned EQU 12 kMPAllocateMaxAlignment EQU 16 ; Somewhat arbitrary limit on expectations. kMPAllocateAltiVecAligned EQU 4 ; The P.C. name. kMPAllocateVMXAligned EQU 4 ; The older, common name. kMPAllocateVMPageAligned EQU 254 ; Pseudo value, converted at runtime. kMPAllocateInterlockAligned EQU 255 ; Pseudo value, converted at runtime. ; Values for the options parameter to MPAllocateAligned. kMPAllocateClearMask EQU $0001 ; Zero the allocated block. kMPAllocateGloballyMask EQU $0002 ; Allocate from the globally visible pool. kMPAllocateResidentMask EQU $0004 ; Allocate from the RAM-resident pool. kMPAllocateNoGrowthMask EQU $0010 ; Do not attempt to grow the pool. ; ------------------------------------------------------------------------------------------- ; ; extern LogicalAddress MPAllocateAligned(ByteCount size, UInt8 alignment, OptionBits options) ; IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN IMPORT_CFM_FUNCTION MPAllocateAligned ENDIF ; ! MPAllocateAligned is new in version 2.0. ; ; extern LogicalAddress MPAllocate(ByteCount size) ; IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN IMPORT_CFM_FUNCTION MPAllocate ENDIF ; Use MPAllocateAligned instead. ; ; extern void MPFree(LogicalAddress object) ; IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN IMPORT_CFM_FUNCTION MPFree ENDIF ; ; extern ByteCount MPGetAllocatedBlockSize(LogicalAddress object) ; IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN IMPORT_CFM_FUNCTION MPGetAllocatedBlockSize ENDIF ; ------------------------------------------------------------------------------------------- ; ; extern void MPBlockCopy(LogicalAddress source, LogicalAddress destination, ByteCount size) ; IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN IMPORT_CFM_FUNCTION MPBlockCopy ENDIF ; ; extern void MPBlockClear(LogicalAddress address, ByteCount size) ; IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN IMPORT_CFM_FUNCTION MPBlockClear ENDIF ; ! MPBlockClear is new in version 2.0. ; ; extern void MPDataToCode(LogicalAddress address, ByteCount size) ; IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN IMPORT_CFM_FUNCTION MPDataToCode ENDIF ; ! MPDataToCode is new in version 2.0. ; § ; =========================================================================================== ; Exception/Debugging Services ; ============================ ; ------------------------------------------------------------------------------------------- ; *** Important Note *** ; ---------------------- ; ; The functions MPExtractTaskState and MPSetTaskState infer the size of the "info" buffer ; from the "kind" parameter. A given value for MPTaskStateKind will always refer to a ; single specific physical buffer layout. Should new register sets be added, or the size ; or number of any registers change, new values of MPTaskStateKind will be introduced to ; refer to the new buffer layouts. The types for the buffers are in MachineExceptions. ; ; The correspondence between MPTaskStateKind values and MachineExceptions types is: ; ; kMPTaskStateRegisters -> RegisterInformation ; kMPTaskStateFPU -> FPUInformation ; kMPTaskStateVectors -> VectorInformation ; kMPTaskStateMachine -> MachineInformation ; kMPTaskState32BitMemoryException -> ExceptionInfo for old-style 32-bit memory exceptions ; ; For reference, on PowerPC the MachineExceptions types contain: ; ; RegisterInformation -> The GPRs, 32 values of 64 bits each. ; FPUInformation -> The FPRs plus FPSCR, 32 values of 64 bits each, one value of ; 32 bits. ; VectorInformation -> The AltiVec vector registers plus VSCR and VRSave, 32 values ; of 128 bits each, one value of 128 bits, and one 32 bit value. ; MachineInformation -> The CTR, LR, PC, each of 64 bits. The CR, XER, MSR, MQ, ; exception kind, and DSISR, each of 32 bits. The 64 bit DAR. ; ExceptionInfo -> Only memory exceptions are specified, 4 fields of 32 bits each. ; Note that this type only covers memory exceptions on 32-bit CPUs! ; Values for the TaskStateKind to MPExtractTaskState and MPSetTaskState. kMPTaskStateRegisters EQU 0 ; The task general registers. kMPTaskStateFPU EQU 1 ; The task floating point registers kMPTaskStateVectors EQU 2 ; The task vector registers kMPTaskStateMachine EQU 3 ; The task machine registers kMPTaskState32BitMemoryException EQU 4 ; The task memory exception information for 32-bit CPUs. ; Option bits and numbers for MPDisposeTaskException. kMPTaskPropagate EQU 0 ; The exception is propagated. kMPTaskResumeStep EQU 1 ; The task is resumed and single step is enabled. kMPTaskResumeBranch EQU 2 ; The task is resumed and branch stepping is enabled. kMPTaskResumeMask EQU $0000 ; The task is resumed. kMPTaskPropagateMask EQU $01 ; The exception is propagated. kMPTaskResumeStepMask EQU $02 ; The task is resumed and single step is enabled. kMPTaskResumeBranchMask EQU $04 ; The task is resumed and branch stepping is enabled. ; ------------------------------------------------------------------------------------------- ; ; extern OSStatus MPSetExceptionHandler(MPTaskID task, MPQueueID exceptionQ) ; IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN IMPORT_CFM_FUNCTION MPSetExceptionHandler ENDIF ; ; extern OSStatus MPThrowException(MPTaskID task, MPExceptionKind kind) ; IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN IMPORT_CFM_FUNCTION MPThrowException ENDIF ; ; extern OSStatus MPDisposeTaskException(MPTaskID task, OptionBits action) ; IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN IMPORT_CFM_FUNCTION MPDisposeTaskException ENDIF ; ; extern OSStatus MPExtractTaskState(MPTaskID task, MPTaskStateKind kind, void *info) ; IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN IMPORT_CFM_FUNCTION MPExtractTaskState ENDIF ; ; extern OSStatus MPSetTaskState(MPTaskID task, MPTaskStateKind kind, void *info) ; IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN IMPORT_CFM_FUNCTION MPSetTaskState ENDIF ; ------------------------------------------------------------------------------------------- ; ; extern OSStatus MPRegisterDebugger(MPQueueID queue, MPDebuggerLevel level) ; IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN IMPORT_CFM_FUNCTION MPRegisterDebugger ENDIF ; ; extern OSStatus MPUnregisterDebugger(MPQueueID queue) ; IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN IMPORT_CFM_FUNCTION MPUnregisterDebugger ENDIF ; § ; =========================================================================================== ; Remote Call Services ; ==================== ; typedef UInt8 MPRemoteContext kMPAnyRemoteContext EQU 0 kMPOwningProcessRemoteContext EQU 1 ; ; extern void *MPRemoteCall(MPRemoteProcedure remoteProc, void *parameter, MPRemoteContext context) ; IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN IMPORT_CFM_FUNCTION MPRemoteCall ENDIF ; ! MPRemoteCall is new in version 2.0. ; § ; =========================================================================================== ; Checking API Availability ; ========================= ; =========================================================================================== ; *** WARNING: You must properly check the availability of MP services before calling them! ; =========================================================================================== ; ; Checking for the availability of the MP API is rather ugly. This is a historical problem, ; caused by the original implementation letting itself get prepared when it really wasn't ; usable and complicated by some important clients then depending on weak linking to "work". ; (And further complicated by CFM not supporting "deferred" imports, which is how many ; programmers think weak imports work.) ; ; The end result is that the MP API library may get prepared by CFM but be totally unusable. ; This means that if you import from the MP API library, you cannot simply check for a ; resolved import to decide if MP services are available. Worse, if you explicitly prepare ; the MP API library you cannot assume that a noErr result from GetSharedLibrary means that ; MP services are available. ; ; • If you import from the MP API library you MUST: ; ; Use the MPLibraryIsLoaded macro (or equivalent code in languages other than C) to tell ; if the MP API services are available. It is not sufficient to simply check that an ; imported symbol is resolved as is commonly done for other libraries. The macro expands ; to the expression: ; ; ( ( (UInt32)_MPIsFullyInitialized != (UInt32)kUnresolvedCFragSymbolAddress ) && ; ( _MPIsFullyInitialized () ) ) ; ; This checks if the imported symbol _MPIsFullyInitialized is resolved and if resolved ; calls it. Both parts must succeed for the MP API services to be available. ; ; • If you explicitly prepare the MP API library you MUST: ; ; Use code similar to the following example to tell if the MP API services are available. ; It is not sufficient to depend on just a noErr result from GetSharedLibrary. ; ; OSErr err; ; Boolean mpIsAvailable = false; ; CFragConnectionID connID = kInvalidID; ; MPIsFullyInitializedProc mpIsFullyInitialized = NULL; ; ; err = GetSharedLibrary ( "\pMPLibrary", kCompiledCFragArch, kReferenceCFrag, ; &connID, NULL, NULL ); ; ; if ( err == noErr ) { ; err = FindSymbol ( connID, "\p_MPIsFullyInitialized", ; (Ptr *) &mpIsFullyInitialized, NULL ); ; } ; ; if ( err == noErr ) { ; mpIsAvailable = (* mpIsFullyInitialized) (); ; } ; ; =========================================================================================== ; ; extern Boolean _MPIsFullyInitialized(void ) ; IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN IMPORT_CFM_FUNCTION _MPIsFullyInitialized ENDIF ; =========================================================================================== ; The MPLibraryIsLoaded service is a macro under C that expands to the logical expression: ; ( (UInt32)MPProcessors != (UInt32)kUnresolvedCFragSymbolAddress ) ; The intention is to check if the imported symbol MPProcessors is resolved. For other ; languages use the equivalent expression. ; =========================================================================================== ; § ; =========================================================================================== ; Miscellaneous Services ; ====================== ; ; extern void _MPLibraryVersion(const char **versionCString, UInt32 *major, UInt32 *minor, UInt32 *release, UInt32 *revision) ; IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN IMPORT_CFM_FUNCTION _MPLibraryVersion ENDIF ; § ; =========================================================================================== ; Unofficial Services ; =================== ; =========================================================================================== ; *** WARNING *** ; These services are not part of the officially documented multiprocessing API. They may not ; be avaliable in future versions of Mac OS multiprocessing support, or in environments that ; have a different underlying OS architecture such as Mac OS on top of a microkernel, the ; Mac OS Blue Box under Mac OS X, native MP support in Mac OS X, etc. ; =========================================================================================== ; ; extern LogicalAddress _MPAllocateSys(ByteCount size) ; IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN IMPORT_CFM_FUNCTION _MPAllocateSys ENDIF ; Use MPAllocateAligned instead. ; ; extern void *_MPRPC(MPRemoteProcedure remoteProc, void *parameter) ; IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN IMPORT_CFM_FUNCTION _MPRPC ENDIF ; Use _MPRemoteCall instead. ; ; extern Boolean _MPTaskIsToolboxSafe(MPTaskID task) ; IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN IMPORT_CFM_FUNCTION _MPTaskIsToolboxSafe ENDIF ; ; extern Boolean _MPLibraryIsCompatible(const char *versionCString, UInt32 major, UInt32 minor, UInt32 release, UInt32 revision) ; IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN IMPORT_CFM_FUNCTION _MPLibraryIsCompatible ENDIF ; § ; =========================================================================================== ; Defunct Services ; ================ IF &TYPE('MPIncludeDefunctServices') = 'UNDEFINED' THEN MPIncludeDefunctServices: SET 0 ENDIF IF MPIncludeDefunctServices THEN ; ; extern void _MPDebugStr(ConstStr255Param msg) ; IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN IMPORT_CFM_FUNCTION _MPDebugStr ENDIF ; ; extern StringPtr _MPStatusPString(OSStatus status) ; IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN IMPORT_CFM_FUNCTION _MPStatusPString ENDIF ; ; extern const char *_MPStatusCString(OSStatus status) ; IF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN IMPORT_CFM_FUNCTION _MPStatusCString ENDIF ENDIF ; MPIncludeDefunctServices ; =========================================================================================== ENDIF ; __MULTIPROCESSING__